HTTP/2: per-stream idle timeout #581

arturobernalg · 2025-12-07T15:07:07Z

This change introduces per-stream idle and lifetime timeouts enforced by the HTTP/2 core multiplexer. Streams that exceed the configured limits are reset with H2StreamTimeoutException, while the underlying HTTP/2 connection remains usable for other streams.

Configuration is exposed via H2Config.setStreamIdleTimeout and setStreamLifetimeTimeout and is disabled by default, so existing users see no behaviour change unless they opt in. H2Stream now tracks creation and last-activity timestamps, and AbstractH2StreamMultiplexer inspects those on I/O events to apply the timeouts without background threads.

rschmitt · 2025-12-09T01:25:32Z

What kinds of timeouts are currently supported with HTTP/2?
Is H2Config the correct place to put these options, since they are not conceptually specific to HTTP/2?

arturobernalg · 2025-12-09T08:09:08Z

What kinds of timeouts are currently supported with HTTP/2?

Is H2Config the correct place to put these options, since they are not conceptually specific to HTTP/2?

At the moment we only expose connection-level timeouts (for example via IOReactorConfig socket and session timeouts); there is no existing notion of per-stream timeout in the HTTP/2 code.
These new options are enforced entirely inside the HTTP/2 stream multiplexer, so they are scoped to HTTP/2 stream semantics and therefore live in H2Config.
If we ever want similar per-message timeouts for other protocols, we can add a higher-level abstraction then without changing this API.

rschmitt · 2025-12-09T17:43:59Z

If we ever want similar per-message timeouts for other protocols, we can add a higher-level abstraction then without changing this API.

What about RequestConfig#setResponseTimeout? The Javadoc seems to indicate that that option is supported everywhere but HTTP/2. Should we start by backfilling multiplexer support for this specific setting?

arturobernalg · 2025-12-09T17:52:30Z

If we ever want similar per-message timeouts for other protocols, we can add a higher-level abstraction then without changing this API.

What about RequestConfig#setResponseTimeout? The Javadoc seems to indicate that that option is supported everywhere but HTTP/2. Should we start by backfilling multiplexer support for this specific setting?

RequestConfig#setResponseTimeout IMO lives in the client API, while H2Config is a transport-level setting in Core. I would keep this change scoped to Core and then look at wiring responseTimeout onto an appropriate per-stream timeout in the httpclient5 layer as a follow-up

ok2c · 2025-12-10T10:14:31Z

@arturobernalg @rschmitt This timeout value / these timeout values must be settable / mutable at runtime exactly the same way as Socket read timeout. Just setting an initial value from a config bean is not good enough. At the client level the request execution pipeline could use that API to apply RequestConfig#responseTimeout at the initiation of the message exchange

arturobernalg · 2025-12-10T10:59:36Z

@arturobernalg @rschmitt This timeout value / these timeout values must be settable / mutable at runtime exactly the same way as Socket read timeout. Just setting an initial value from a config bean is not good enough. At the client level the request execution pipeline could use that API to apply RequestConfig#responseTimeout at the initiation of the message exchange

@ok2c Makes sense. I can treat the timeouts in H2Config as defaults and keep the actual per-stream timeout state on H2Stream.
I will expose a small control API on H2StreamChannel so the client execution pipeline can set / mutate idle / lifetime timeouts at the start of an exchange and map RequestConfig#responseTimeout to the stream lifetime there.

ok2c · 2025-12-10T11:48:40Z

I can treat the timeouts in H2Config as defaults

@arturobernalg I agree with @rschmitt that is the wrong place for timeout settings. Those are meant to be H2 protocol related configs. Please use connection socket timeout as an initial / default value.

arturobernalg · 2025-12-10T19:15:01Z

I can treat the timeouts in H2Config as defaults

@arturobernalg I agree with @rschmitt that is the wrong place for timeout settings. Those are meant to be H2 protocol related configs. Please use connection socket timeout as an initial / default value.

@rschmitt @ok2c please another pass

rschmitt · 2025-12-10T19:28:07Z

I'd like to see HTTP/2 test coverage added to httpclient5-testing/src/test/java/org/apache/hc/client5/testing/async/TestAsyncSocketTimeout.java in the client integration tests. This would provide at least some assurance that we are implementing a consistent contract across the various transports and protocols.

ok2c · 2025-12-10T20:10:42Z

I'd like to see HTTP/2 test coverage added to httpclient5-testing/src/test/java/org/apache/hc/client5/testing/async/TestAsyncSocketTimeout.java in the client integration tests. This would provide at least some assurance that we are implementing a consistent contract across the various transports and protocols.

@rschmitt That is fair, but the feature would need to have been made available in an alpha release of core or the timeout tests would need to be ported to core.

arturobernalg · 2025-12-11T11:56:09Z

I'd like to see HTTP/2 test coverage added to httpclient5-testing/src/test/java/org/apache/hc/client5/testing/async/TestAsyncSocketTimeout.java in the client integration tests. This would provide at least some assurance that we are implementing a consistent contract across the various transports and protocols.

@rschmitt I’ve added an async core HTTP/2 socket-timeout test in httpcore5-testing (AsyncH2SocketTimeoutCoreTest) that mirrors the client-side TestAsyncSocketTimeout behaviour. It verifies that a per-request timeout over HTTP/2 results in HttpStreamResetException, so I believe this covers the contract you were asking for – let me know if you had something different in mind.

ok2c · 2025-12-14T09:16:58Z

@arturobernalg Please rebase this change-set off the latest master and I will review it

arturobernalg · 2025-12-14T18:35:43Z

@arturobernalg Please rebase this change-set off the latest master and I will review it

@ok2c please take a look

rschmitt · 2025-12-17T18:37:32Z

@rschmitt I’ve added an async core HTTP/2 socket-timeout test in httpcore5-testing (AsyncH2SocketTimeoutCoreTest) that mirrors the client-side TestAsyncSocketTimeout behaviour. It verifies that a per-request timeout over HTTP/2 results in HttpStreamResetException, so I believe this covers the contract you were asking for – let me know if you had something different in mind.

Ideally I'd like to see contract testing, i.e. the same test cases running for HTTP, HTTPS, h2, and h2c. This ensures that the high-level API behaves consistently across the various implementations; it's also a very effective way of asserting that the various config options are being propagated and applied correctly throughout the client's internals. This is most effectively done through tests in httpclient5 (which has the issue that Oleg pointed out, unless you are backfilling a feature into existing APIs).

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2StreamTimeoutException.java

ok2c · 2025-12-21T15:27:50Z

@arturobernalg Please try to minimize changes to H2 protocol code. More functionality can be added incrementally at a later point. Try to keep it small and lean.

arturobernalg · 2025-12-22T08:18:22Z

@arturobernalg Please try to minimize changes to H2 protocol code. More functionality can be added incrementally at a later point. Try to keep it small and lean.

@ok2c please another pass

ok2c · 2025-12-22T17:40:14Z

@arturobernalg Better, but please look at all my comments

ok2c · 2026-01-19T10:50:40Z

@arturobernalg Please re-open and rebase this change-set off the latest master. This is presently more important than other open pull requests in core

arturobernalg · 2026-01-19T14:32:17Z

@arturobernalg Please re-open and rebase this change-set off the latest master. This is presently more important than other open pull requests in core

@ok2c done

...ore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/bootstrap/CancellableExecution.java

Expose configuration via H2Config, throw H2StreamTimeoutException on expiry and keep the connection alive Extend test coverage and add an example client demonstrating timed-out and successful streams

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/H2Stream.java

httpcore5/src/main/java/org/apache/hc/core5/reactor/IOSessionImpl.java

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java

httpcore5-h2/src/test/java/org/apache/hc/core5/http2/examples/H2StreamTimeoutClientExample.java

ok2c

@arturobernalg Almost there.

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2StreamTimeoutException.java

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2StreamTimeoutException.java

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/H2Stream.java

rschmitt · 2026-01-22T21:39:10Z

...e5-testing/src/test/java/org/apache/hc/core5/testing/async/AsyncH2SocketTimeoutCoreTest.java

+                .setTlsStrategy(new H2ServerTlsStrategy(SSLTestContexts.createServerSSLContext()))
+                .setIOReactorConfig(
+                        IOReactorConfig.custom()
+                                .setSoTimeout(Timeout.ofSeconds(30))


There's also ConnectionConfig#setSocketConfig and RequestConfig#setResponseTimeout. Will those config values also get threaded into this implementation, the way they are in HTTP/1.1? (Note the precedence rules: ConnectionConfig overrides SocketConfig, and responseTimeout overrides socket timeouts.)

@rschmitt Once this feature has been made available in client, client level configs will be used to set the idle timeout value for H2 streams.

rschmitt · 2026-01-22T21:40:41Z

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2StreamTimeoutException.java

+ *
+ * @since 5.5
+ */
+public class H2StreamTimeoutException extends InterruptedIOException {


Any reason not to just subclass or reuse java.net.SocketTimeoutException?

@rschmitt But this exception does not represent a socket timeout. It is a different timeout by origin and as such it extends InterruptedIOException but not SocketTimeoutException. This enables the caller to differentiate socket timeouts that affect the entire connection and all its H2 streams from an individual H2 stream timeout.

I guess that's reasonable

rschmitt · 2026-01-22T21:42:24Z

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/H2Stream.java

-        // not supported
+        this.idleTimeout = timeout;


This is so satisfying to see! I think this is the ideal outcome: zero API changes (except for the new exception type), backfilling missing support for existing APIs, improving consistency across protocols, etc.

@rschmitt Unfortunately this is not quite the case. I was unable to articulate to @arturobernalg exactly what API changes I wanted, so I ended up implementing them in a separate commit.

; Handle cancelled SelectionKey in interestOps access

arturobernalg requested a review from ok2c December 7, 2025 15:07

arturobernalg force-pushed the h2Stream branch 2 times, most recently from 2f5d095 to 31bbf5b Compare December 10, 2025 18:56

arturobernalg force-pushed the h2Stream branch 2 times, most recently from c6364c8 to d7b8e8b Compare December 14, 2025 18:34

arturobernalg force-pushed the h2Stream branch 3 times, most recently from b60f8b0 to ccf73f8 Compare December 15, 2025 12:31

ok2c requested changes Dec 21, 2025

View reviewed changes

arturobernalg force-pushed the h2Stream branch from 084cab8 to 5cd4675 Compare December 22, 2025 08:16

arturobernalg requested a review from ok2c December 22, 2025 08:18

arturobernalg force-pushed the h2Stream branch from ee03f78 to e627911 Compare December 22, 2025 08:49

arturobernalg force-pushed the h2Stream branch from 8534aa0 to 8cf5233 Compare December 22, 2025 19:10

arturobernalg reopened this Jan 19, 2026

arturobernalg force-pushed the h2Stream branch from 8cf5233 to 127a32f Compare January 19, 2026 10:55

ok2c reviewed Jan 19, 2026

View reviewed changes

...ore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/bootstrap/CancellableExecution.java Outdated Show resolved Hide resolved

arturobernalg force-pushed the h2Stream branch from 978dfae to ce72c8c Compare January 19, 2026 19:04

arturobernalg requested a review from ok2c January 19, 2026 19:05

HTTP/2: add per-stream idle and lifetime timeouts to core multiplexer

26993ee

Expose configuration via H2Config, throw H2StreamTimeoutException on expiry and keep the connection alive Extend test coverage and add an example client demonstrating timed-out and successful streams

arturobernalg force-pushed the h2Stream branch from ce72c8c to a500259 Compare January 20, 2026 18:02

ok2c requested changes Jan 20, 2026

View reviewed changes

arturobernalg force-pushed the h2Stream branch from db30dd0 to ddbdcb0 Compare January 21, 2026 09:12

arturobernalg requested a review from ok2c January 21, 2026 12:04

arturobernalg force-pushed the h2Stream branch 2 times, most recently from 9b09204 to 0078239 Compare January 21, 2026 12:15

ok2c requested changes Jan 21, 2026

View reviewed changes

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java Outdated Show resolved Hide resolved

httpcore5-h2/src/test/java/org/apache/hc/core5/http2/examples/H2StreamTimeoutClientExample.java Outdated Show resolved Hide resolved

arturobernalg force-pushed the h2Stream branch from 2036b6d to 7b11325 Compare January 21, 2026 17:46

ok2c changed the title ~~HTTP/2: add per-stream idle and lifetime timeouts to core multiplexer~~ HTTP/2: per-stream idle timeout Jan 21, 2026

ok2c requested changes Jan 21, 2026

View reviewed changes

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2StreamTimeoutException.java Outdated Show resolved Hide resolved

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/AbstractH2StreamMultiplexer.java Show resolved Hide resolved

arturobernalg force-pushed the h2Stream branch from 3d28c0e to d3008c2 Compare January 22, 2026 08:18

arturobernalg requested a review from ok2c January 22, 2026 08:19

ok2c reviewed Jan 22, 2026

View reviewed changes

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/H2StreamTimeoutException.java Outdated Show resolved Hide resolved

arturobernalg force-pushed the h2Stream branch from 37287aa to c626e45 Compare January 22, 2026 18:13

ok2c approved these changes Jan 22, 2026

View reviewed changes

httpcore5-h2/src/main/java/org/apache/hc/core5/http2/impl/nio/H2Stream.java Outdated Show resolved Hide resolved

rschmitt reviewed Jan 22, 2026

View reviewed changes

arturobernalg force-pushed the h2Stream branch from 833cd2a to 3d532a2 Compare January 23, 2026 10:38

arturobernalg requested a review from rschmitt January 23, 2026 10:38

add per-stream idle timeout and suppress CancelledKeyException on cancel

becade0

; Handle cancelled SelectionKey in interestOps access

arturobernalg force-pushed the h2Stream branch from a697f1b to becade0 Compare January 24, 2026 06:08

HTTP/2: per-stream idle timeout #581

Are you sure you want to change the base?

HTTP/2: per-stream idle timeout #581

Uh oh!

Conversation

arturobernalg commented Dec 7, 2025

Uh oh!

rschmitt commented Dec 9, 2025

Uh oh!

arturobernalg commented Dec 9, 2025

Uh oh!

rschmitt commented Dec 9, 2025

Uh oh!

arturobernalg commented Dec 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ok2c commented Dec 10, 2025

Uh oh!

arturobernalg commented Dec 10, 2025

Uh oh!

ok2c commented Dec 10, 2025

Uh oh!

arturobernalg commented Dec 10, 2025

Uh oh!

rschmitt commented Dec 10, 2025

Uh oh!

ok2c commented Dec 10, 2025

Uh oh!

arturobernalg commented Dec 11, 2025

Uh oh!

ok2c commented Dec 14, 2025

Uh oh!

arturobernalg commented Dec 14, 2025

Uh oh!

rschmitt commented Dec 17, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ok2c commented Dec 21, 2025

Uh oh!

arturobernalg commented Dec 22, 2025

Uh oh!

ok2c commented Dec 22, 2025

Uh oh!

ok2c commented Jan 19, 2026

Uh oh!

arturobernalg commented Jan 19, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ok2c left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rschmitt Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

ok2c Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

rschmitt Jan 22, 2026

Choose a reason for hiding this comment

Uh oh!

ok2c Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

rschmitt Jan 23, 2026

Choose a reason for hiding this comment

Uh oh!

rschmitt Jan 22, 2026

arturobernalg commented Dec 9, 2025 •

edited

Loading